Harness 工程顶级教程：定制开发你的AI助手
资源篇。Agent 部分 课程只带你入了门，真正要做开发的伙伴重点看 Mastra 框架；如果你对原理感兴趣，这份 Vercel 的 Harness 工程教程值得完整跟一遍。本节讲清楚：这教程是什么、为什么值得学、怎么跟学效率最高。
这份教程是什么
Vercel 官方 Academy 的 Build Your Own AI Coding Agent Harness（原文：vercel.com/academy/build-ai-agent-harness），用 AI SDK + Vercel Sandbox + just-bash 技术栈，从零构建一个 AI 编码代理框架（Agent Harness），共 38 课。
课程资料的 demos/build-harness/ 目录里有全部 38 课的中文译文，原文的技术术语（Agent Harness / Sandbox / Approval Gates 等）在译文里保留了中英文对照。
先诚实披露一个纠结点：这份教程本质上是 Vercel 封装好的 SDK 的教学（和 Mastra 一样，是为了让你用它的东西而准备的环境），但它里面的所有基础知识、所有工具实现，都与 Harness Engineering 高度关联——这正是推荐它的理由。
Harness Engineering 到底在驾驭什么
一句话：让 AI 按照我们预想好的工具环境和工作流，自己去把这些环境协调好——AI 自己管理自己，这就是"驾驭工程"。
为什么必须懂这些底层？不懂直接让 AI 上手 Mastra，它其实也能做出来，但做出来的东西会是一个半成品。半成品长什么样？就是我们前几节的 playground 本身：左侧会话列表没有智能重命名，消息区没有历史会话、没有重新发送、没有重新生成、没有复制、没有编辑消息——这些坑点（15-03 列过三个）就是"考虑不周全"的实证。
为什么考虑不周全？因为 AI 有上下文限制：一个窗口里不可能把所有东西一次性全搞定。这时需要你作为整个项目的规划者——从上帝视角——把这些全部预想好，再分批告诉 AI 去完成。Mastra 把所有工具都给你做好了，但你的思维要跟上 AI，否则 AI 做的东西永远是半成品。
教程的出彩之处：八大部分全覆盖
这份教程把 Harness Engineering 的核心八大部分全部讲清楚了——这也正是所谓"企业级工程化应用"的知识版图：
| 核心部分 | 回答的问题 | 对应课程（中文译文章节） |
|---|---|---|
| 工具循环 | 一个工具如何让聊天机器人变成代理 | 01-03 |
| 工具设计 | 工具描述即模型选择 API；危险工具的安全门控 | 04-06 |
| 系统提示词 | 代理能力 + 行为边界，动态构建适应运行时 | 07-10（含 AGENTS.md 项目上下文） |
| 沙箱抽象 | 统一执行环境接口（本地/内存/云端三种实现） | 11-15 |
| 上下文修剪 | 控制 token 线性增长，工具输出上限 | 16-19 |
| 子代理委托 | 单代理失败模式与多代理协作 | 20-23 |
| 生命周期管理 | 状态机、快照恢复、持久化工作流 | 24-27 |
| 可扩展性 | 结构化提问、待办工具、Skills 系统、自定义工具、扩展点 | 28-38 |
有了这张地图再去设计你的 AI 或智能体，就不再是"想到哪做到哪"，而是每个部位都有对应的工程手段。
落地到第一个工具：其实非常简单
听起来复杂，落地到第一个工具应用时只有三步：用 tool SDK 约束输入内容和工具描述 → 定义提示词 → 写工具方法的具体执行。教程第 1、2 课的实战（译文摘录）：
// 第 1 课：给代理一个 read 工具，把"自信的实习生"变成真正会打开文件的东西
import { ToolLoopAgent, stepCountIs, tool } from "ai";
import { z } from "zod";
const agent = new ToolLoopAgent({
instructions: "...",
model: "anthropic/claude-haiku-4-5",
tools: [read],
stopWhen: stepCountIs(10), // 步数上限，防无限循环（与 15-02 Orchestrator 的 10 步同款思路）
});
const read = tool({
description: "...", // 给模型的提示词，不是文档字符串——模型读它来决定何时调用
inputSchema: z.object({
path: z.string(),
offset: z.number().optional(),
limit: z.number().optional(),
}),
execute: async ({ path }) => {
// 相对于工作目录解析路径，使代理无法读取项目外文件
// 输出限制 500 行，每行加行号前缀
},
});
ts
第 2 课的精髓是工具描述的四部分约定：WHEN TO USE / WHEN NOT TO USE / DO NOT USE FOR / EXAMPLES——两个工具（read 与 grep）之间模型怎么路由，完全由描述决定。教程的说法很精准：描述是模型选择工具的 API，为模型编写描述，而不是为读者编写。这与 16-02 三份提示词口径一致的原则同源，只是用在工具描述上。
底层原理：值得让 AI 讲给你听
除了用好 tool()，强烈建议看一下 Vercel 的 tool 具体实现——怎么把这些抽象概念衔接起来的。你可以把源码丢给 AI，让它读 tool 的逻辑讲给你听（"让 AI 读代码"是第 8 章就用熟的方法）。读完会发现底层没有魔法：一方面告诉 AI 有哪些工具可用，另一方面最底层就是按约定的格式让 AI 响应函数调用（早期的实现甚至是正则匹配解析出来的）。把这个流程看一遍，Harness 就祛魅了——和 15-03 拆解 Mastra 工具机制是同一件事的两个视角。
跟学路径建议
具体到操作层面：
- 每个代码部分都实践一遍。教程的动手练习设计得很好（要求清单 + 实现提示），从 read 工具到 grep 再到审批门控，每课的代码量都不大。
- 每个部分浏览一遍、有概念即可。不需要 38 课全部精读——像沙箱的云端实现、持久化工作流这类章节，知道它解决什么问题、方案长什么样就行。
- 有了概念后，借助 AI 完成设计。工具的设计、沙箱的设计、工具循环的设计、提示词的设计——这些你在教程里见过成品，再让 AI 帮你落地时，你就知道该验收什么。与 15-03"上帝视角规划"完全呼应：先见过好样子，才能指挥 AI 做出好样子。
与 16 章的分工（避免重复学）
教程第 20-23 课（为什么委托 / Explorer 子代理 / 执行者子代理 / task 工具）的精华，课程已在 16-03 以"手搓 task 工具 vs Mastra 原生 Supervisor"对比展开（Explorer 只读工具+轻模型+5 步预算，Executor 全量工具+强模型+15 步预算，分界线是"能不能改东西"）。本节不重复，学到 16-03 时回看教程原文章节即可对上。后续课程还会挑 Harness Engineering 里相对重要的几个部分单独讲，再扩展 MCP 与工具链能力——本教程是那一切的底图。
怎么比别人快一步
你和其他用 AI 的开发者拉开差距的地方，无非两处：
- 前期考虑的全面度——投入时间不同、使用的模型能力不同，规划质量就有差异。对冲办法：了解最新 Harness Engineering 生态里工具有哪些变化，优先学习优质的、效率高的环境和工具，更快应用到项目里让 AI 辅助你。始终比别人快一步、走在工具与前沿技术的前面，一方面打消技术洪流对你的冲击，另一方面对冲这波浪潮对程序员的影响。
- 自己的思考密度——不光在课程 Q 群交流，还要关注社区里大牛们在干什么，自己动手做一些东西。教程给的是地图，路要自己走。
小结
- 教程：Vercel Academy build-ai-agent-harness，38 课中文全译文在
demos/build-harness/，技术栈 AI SDK + Vercel Sandbox + just-bash - Harness Engineering = 让 AI 在预想的工具环境与工作流里自己管理自己；不懂底层直接让 AI 上框架，产出必是半成品（playground 自己就是例证）
- 八大板块：工具循环 / 工具设计 / 系统提示词 / 沙箱抽象 / 上下文修剪 / 子代理委托 / 生命周期管理 / 可扩展性
- 第一个工具三步走：tool() 约束输入与描述 → 提示词 → 执行方法；工具描述用四部分约定（WHEN TO USE / WHEN NOT TO USE / DO NOT USE FOR / EXAMPLES）
- 跟学路径：逐课实践 → 浏览建概念 → 借 AI 设计；委托四课（20-23）的精华在 16-03 展开，不必在此精读
第15章到此结束。下一章讲 AI Agents 系统——自主决策的智能助手引擎。
↑